<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Streaming Replication Protocol</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REV="MADE"
HREF="mailto:pgsql-docs@postgresql.org"><LINK
REL="HOME"
TITLE="PostgreSQL 9.1.2 Documentation"
HREF="index.html"><LINK
REL="UP"
TITLE="Frontend/Backend Protocol"
HREF="protocol.html"><LINK
REL="PREVIOUS"
TITLE="Message Flow"
HREF="protocol-flow.html"><LINK
REL="NEXT"
TITLE="Message Data Types"
HREF="protocol-message-types.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="stylesheet.css"><META
HTTP-EQUIV="Content-Type"
CONTENT="text/html; charset=ISO-8859-1"><META
NAME="creation"
CONTENT="2011-12-01T22:07:59"></HEAD
><BODY
CLASS="SECT1"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="5"
ALIGN="center"
VALIGN="bottom"
><A
HREF="index.html"
>PostgreSQL 9.1.2 Documentation</A
></TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
TITLE="Message Flow"
HREF="protocol-flow.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="top"
><A
HREF="protocol.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="60%"
ALIGN="center"
VALIGN="bottom"
>Chapter 46. Frontend/Backend Protocol</TD
><TD
WIDTH="20%"
ALIGN="right"
VALIGN="top"
><A
TITLE="Message Data Types"
HREF="protocol-message-types.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="PROTOCOL-REPLICATION"
>46.3. Streaming Replication Protocol</A
></H1
><P
>To initiate streaming replication, the frontend sends the
<TT
CLASS="LITERAL"
>replication</TT
> parameter in the startup message. This tells the
backend to go into walsender mode, wherein a small set of replication commands
can be issued instead of SQL statements. Only the simple query protocol can be
used in walsender mode.

The commands accepted in walsender mode are:

<P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>IDENTIFY_SYSTEM</DT
><DD
><P
>      Requests the server to identify itself. Server replies with a result
      set of a single row, containing three fields:
     </P
><P
>      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>systemid</DT
><DD
><P
>       The unique system identifier identifying the cluster. This
       can be used to check that the base backup used to initialize the
       standby came from the same cluster.
      </P
></DD
><DT
>timeline</DT
><DD
><P
>       Current TimelineID. Also useful to check that the standby is
       consistent with the master.
      </P
></DD
><DT
>xlogpos</DT
><DD
><P
>       Current xlog write location. Useful to get a known location in the
       transaction log where streaming can start.
      </P
></DD
></DL
></DIV
><P>
     </P
></DD
><DT
>START_REPLICATION <TT
CLASS="REPLACEABLE"
><I
>XXX</I
></TT
>/<TT
CLASS="REPLACEABLE"
><I
>XXX</I
></TT
></DT
><DD
><P
>      Instructs server to start streaming WAL, starting at
      WAL position <TT
CLASS="REPLACEABLE"
><I
>XXX</I
></TT
>/<TT
CLASS="REPLACEABLE"
><I
>XXX</I
></TT
>.
      The server can reply with an error, e.g. if the requested section of WAL
      has already been recycled. On success, server responds with a
      CopyBothResponse message, and then starts to stream WAL to the frontend.
      WAL will continue to be streamed until the connection is broken;
      no further commands will be accepted.
     </P
><P
>      WAL data is sent as a series of CopyData messages.  (This allows
      other information to be intermixed; in particular the server can send
      an ErrorResponse message if it encounters a failure after beginning
      to stream.)  The payload in each CopyData message follows this format:
     </P
><P
>      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>XLogData (B)</DT
><DD
><P
>      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Byte1('w')</DT
><DD
><P
>          Identifies the message as WAL data.
      </P
></DD
><DT
>Byte8</DT
><DD
><P
>          The starting point of the WAL data in this message, given in
          XLogRecPtr format.
      </P
></DD
><DT
>Byte8</DT
><DD
><P
>          The current end of WAL on the server, given in
          XLogRecPtr format.
      </P
></DD
><DT
>Byte8</DT
><DD
><P
>          The server's system clock at the time of transmission,
          given in TimestampTz format.
      </P
></DD
><DT
>Byte<TT
CLASS="REPLACEABLE"
><I
>n</I
></TT
></DT
><DD
><P
>          A section of the WAL data stream.
      </P
></DD
></DL
></DIV
><P>
      </P
></DD
></DL
></DIV
><P>
     </P
><P
>       A single WAL record is never split across two CopyData messages.
       When a WAL record crosses a WAL page boundary, and is therefore
       already split using continuation records, it can be split at the page
       boundary. In other words, the first main WAL record and its
       continuation records can be sent in different CopyData messages.
     </P
><P
>       Note that all fields within the WAL data and the above-described header
       will be in the sending server's native format.  Endianness, and the
       format for the timestamp, are unpredictable unless the receiver has
       verified that the sender's system identifier matches its own
       <TT
CLASS="FILENAME"
>pg_control</TT
> contents.
     </P
><P
>       If the WAL sender process is terminated normally (during postmaster
       shutdown), it will send a CommandComplete message before exiting.
       This might not happen during an abnormal shutdown, of course.
     </P
><P
>       The receiving process can send replies back to the sender at any time,
       using one of the following message formats (also in the payload of a
       CopyData message):
     </P
><P
>      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Standby status update (F)</DT
><DD
><P
>      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Byte1('r')</DT
><DD
><P
>          Identifies the message as a receiver status update.
      </P
></DD
><DT
>Byte8</DT
><DD
><P
>          The location of the last WAL byte + 1 received and written to disk
          in the standby, in XLogRecPtr format.
      </P
></DD
><DT
>Byte8</DT
><DD
><P
>          The location of the last WAL byte + 1 flushed to disk in
          the standby, in XLogRecPtr format.
      </P
></DD
><DT
>Byte8</DT
><DD
><P
>          The location of the last WAL byte + 1 applied in the standby, in
          XLogRecPtr format.
      </P
></DD
><DT
>Byte8</DT
><DD
><P
>          The server's system clock at the time of transmission,
          given in TimestampTz format.
      </P
></DD
></DL
></DIV
><P>
      </P
></DD
></DL
></DIV
><P>
     </P
><P
>      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Hot Standby feedback message (F)</DT
><DD
><P
>      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Byte1('h')</DT
><DD
><P
>          Identifies the message as a Hot Standby feedback message.
      </P
></DD
><DT
>Byte8</DT
><DD
><P
>          The server's system clock at the time of transmission,
          given in TimestampTz format.
      </P
></DD
><DT
>Byte4</DT
><DD
><P
>          The standby's current xmin.
      </P
></DD
><DT
>Byte4</DT
><DD
><P
>          The standby's current epoch.
      </P
></DD
></DL
></DIV
><P>
      </P
></DD
></DL
></DIV
><P>
     </P
></DD
><DT
>BASE_BACKUP [<TT
CLASS="LITERAL"
>LABEL</TT
> <TT
CLASS="REPLACEABLE"
><I
>'label'</I
></TT
>] [<TT
CLASS="LITERAL"
>PROGRESS</TT
>] [<TT
CLASS="LITERAL"
>FAST</TT
>] [<TT
CLASS="LITERAL"
>WAL</TT
>] [<TT
CLASS="LITERAL"
>NOWAIT</TT
>]</DT
><DD
><P
>      Instructs the server to start streaming a base backup.
      The system will automatically be put in backup mode before the backup
      is started, and taken out of it when the backup is complete. The
      following options are accepted:
      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
><TT
CLASS="LITERAL"
>LABEL</TT
> <TT
CLASS="REPLACEABLE"
><I
>'label'</I
></TT
></DT
><DD
><P
>          Sets the label of the backup. If none is specified, a backup label
          of <TT
CLASS="LITERAL"
>base backup</TT
> will be used. The quoting rules
          for the label are the same as a standard SQL string with
          <A
HREF="runtime-config-compatible.html#GUC-STANDARD-CONFORMING-STRINGS"
>standard_conforming_strings</A
> turned on.
         </P
></DD
><DT
><TT
CLASS="LITERAL"
>PROGRESS</TT
></DT
><DD
><P
>          Request information required to generate a progress report. This will
          send back an approximate size in the header of each tablespace, which
          can be used to calculate how far along the stream is done. This is
          calculated by enumerating all the file sizes once before the transfer
          is even started, and may as such have a negative impact on the
          performance - in particular it may take longer before the first data
          is streamed. Since the database files can change during the backup,
          the size is only approximate and may both grow and shrink between
          the time of approximation and the sending of the actual files.
         </P
></DD
><DT
><TT
CLASS="LITERAL"
>FAST</TT
></DT
><DD
><P
>          Request a fast checkpoint.
         </P
></DD
><DT
><TT
CLASS="LITERAL"
>WAL</TT
></DT
><DD
><P
>          Include the necessary WAL segments in the backup. This will include
          all the files between start and stop backup in the
          <TT
CLASS="FILENAME"
>pg_xlog</TT
> directory of the base directory tar
          file.
         </P
></DD
><DT
><TT
CLASS="LITERAL"
>NOWAIT</TT
></DT
><DD
><P
>          By default, the backup will wait until the last required xlog
          segment has been archived, or emit a warning if log archiving is
          not enabled. Specifying <TT
CLASS="LITERAL"
>NOWAIT</TT
> disables both
          the waiting and the warning, leaving the client responsible for
          ensuring the required log is available.
         </P
></DD
></DL
></DIV
><P>
     </P
><P
>      When the backup is started, the server will first send two
      ordinary result sets, followed by one or more CopyResponse
      results.
     </P
><P
>      The first ordinary result set contains the starting position of the
      backup, given in XLogRecPtr format as a single column in a single row.
     </P
><P
>      The second ordinary result set has one row for each tablespace.
      The fields in this row are:
      <P
></P
></P><DIV
CLASS="VARIABLELIST"
><DL
><DT
>spcoid</DT
><DD
><P
>          The oid of the tablespace, or <TT
CLASS="LITERAL"
>NULL</TT
> if it's the base
          directory.
         </P
></DD
><DT
>spclocation</DT
><DD
><P
>          The full path of the tablespace directory, or <TT
CLASS="LITERAL"
>NULL</TT
>
          if it's the base directory.
         </P
></DD
><DT
>size</DT
><DD
><P
>          The approximate size of the tablespace, if progress report has
          been requested; otherwise it's <TT
CLASS="LITERAL"
>NULL</TT
>.
         </P
></DD
></DL
></DIV
><P>
     </P
><P
>      After the second regular result set, one or more CopyResponse results
      will be sent, one for PGDATA and one for each additional tablespace other
      than <TT
CLASS="LITERAL"
>pg_default</TT
> and <TT
CLASS="LITERAL"
>pg_global</TT
>. The data in
      the CopyResponse results will be a tar format (using ustar00
      extensions) dump of the tablespace contents. After the tar data is
      complete, a final ordinary result set will be sent.
     </P
><P
>      The tar archive for the data directory and each tablespace will contain
      all files in the directories, regardless of whether they are
      <SPAN
CLASS="PRODUCTNAME"
>PostgreSQL</SPAN
> files or other files added to the same
      directory. The only excluded files are:
      <P
></P
></P><UL
COMPACT="COMPACT"
><LI
STYLE="list-style-type: disc"
><P
>         <TT
CLASS="FILENAME"
>postmaster.pid</TT
>
        </P
></LI
><LI
STYLE="list-style-type: disc"
><P
>         <TT
CLASS="FILENAME"
>postmaster.opts</TT
>
        </P
></LI
><LI
STYLE="list-style-type: disc"
><P
>         <TT
CLASS="FILENAME"
>pg_xlog</TT
>, including subdirectories. If the backup is run
         with wal files included, a synthesized version of pg_xlog will be
         included, but it will only contain the files necessary for the
         backup to work, not the rest of the contents.
        </P
></LI
></UL
><P>
      Owner, group and file mode are set if the underlying filesystem on
      the server supports it.
     </P
><P
>      Once all tablespaces have been sent, a final regular result set will
      be sent. This result set contains the end position of the
      backup, given in XLogRecPtr format as a single column in a single row.
     </P
></DD
></DL
></DIV
><P>&#13;</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="protocol-flow.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="protocol-message-types.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Message Flow</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="protocol.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Message Data Types</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>